home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kactionselector.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-10-08  |  11.7 KB  |  403 lines
  1. /* This file is part of the KDE project
  2.    Copyright (C) 2002 Anders Lund <anders.lund@lund.tdcadsl.dk>
  3.  
  4.    This library is free software; you can redistribute it and/or
  5.    modify it under the terms of the GNU Library General Public
  6.    License version 2 as published by the Free Software Foundation.
  7.  
  8.    This library is distributed in the hope that it will be useful,
  9.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11.    Library General Public License for more details.
  12.  
  13.    You should have received a copy of the GNU Library General Public License
  14.    along with this library; see the file COPYING.LIB.  If not, write to
  15.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16.    Boston, MA 02110-1301, USA.
  17. */
  18.  
  19. #ifndef _KACTION_SELECTOR_H_
  20. #define _KACTION_SELECTOR_H_
  21.  
  22. #include <qwidget.h>
  23.  
  24. #include <kdelibs_export.h>
  25.  
  26. class QListBox;
  27. class QListBoxItem;
  28. class QKeyEvent;
  29. class QEvent;
  30. class QIconSet;
  31.  
  32. class KActionSelectorPrivate;
  33.  
  34. /**
  35.     @short A widget for selecting and arranging actions/objects
  36.  
  37.     This widget allows the user to select from a set of objects and arrange
  38.     the order of the selected ones using two list boxes labeled "Available"
  39.     and "Used" with horizontal arrows in between to move selected objects between
  40.     the two, and vertical arrows on the right to arrange the order of the selected
  41.     objects.
  42.  
  43.     The widget moves objects to the other listbox when doubleclicked if
  44.     the property moveOnDoubleClick is set to true (default). See moveOnDoubleClick()
  45.     and setMoveOnDoubleClick().
  46.  
  47.     The user control the widget using the keyboard if enabled (default),
  48.     see keyboardEnabled.
  49.  
  50.     Note that this may conflist with keyboard selection in the selected list box,
  51.     if you set that to anything else than QListBox::Single (which is the default).
  52.  
  53.     To use it, simply construct an instance and then add items to the two listboxes,
  54.     available through lbAvailable() and lbSelected(). Whenever you want, you can retrieve
  55.     the selected options using QListBox methods on lbSelected().
  56.  
  57.     This way, you can use your own QListBoxItem class, allowing you to easily
  58.     store object data in those.
  59.  
  60.     When an item is moved to a listbox, it is placed below the current item
  61.     of that listbox.
  62.  
  63.     Standard arrow icons are used, but you can use icons of your own choice if desired,
  64.     see setButtonIcon(). It is also possible to set tooltips and whatsthis help
  65.     for the buttons. See setButtonTooltip() and setButtonWhatsThis().
  66.  
  67.     To set whatsthis or tooltips for the listboxes, access them through
  68.     availableListbox() and selectedListBox().
  69.  
  70.     All the moving buttons are automatically set enabled as expected.
  71.  
  72.     Signals are sent each time an item is moved, allowing you to follow the
  73.     users actions if you need to. See addedToSelection(), removedFromSelection(),
  74.     movedUp() and movedDown()
  75.  
  76.     @author Anders Lund <anders@alweb.dk>
  77. */
  78.  
  79. class KDEUI_EXPORT KActionSelector : public QWidget {
  80.   Q_OBJECT
  81.   Q_ENUMS( ButtonIconSize InsertionPolicy )
  82.   Q_PROPERTY( bool moveOnDoubleClick READ moveOnDoubleClick WRITE setMoveOnDoubleClick )
  83.   Q_PROPERTY( bool keyboardEnabled READ keyboardEnabled WRITE setKeyboardEnabled )
  84.   Q_PROPERTY( QString availableLabel READ availableLabel WRITE setAvailableLabel )
  85.   Q_PROPERTY( QString selectedLabel READ selectedLabel WRITE setSelectedLabel )
  86.   Q_PROPERTY( ButtonIconSize buttonIconSize READ buttonIconSize WRITE setButtonIconSize )
  87.   Q_PROPERTY( InsertionPolicy availableInsertionPolicy READ availableInsertionPolicy WRITE setAvailableInsertionPolicy )
  88.   Q_PROPERTY( InsertionPolicy selectedInsertionPolicy READ selectedInsertionPolicy WRITE setSelectedInsertionPolicy )
  89.   Q_PROPERTY( bool showUpDownButtons READ showUpDownButtons WRITE setShowUpDownButtons )
  90.  
  91. public:
  92.   KActionSelector( QWidget *parent=0, const char *name=0 );
  93.   ~KActionSelector();
  94.  
  95.   /**
  96.      @return The QListBox holding the available actions
  97.   */
  98.   QListBox *availableListBox() const;
  99.  
  100.   /**
  101.      @return The QListBox holding the selected actions
  102.   */
  103.   QListBox *selectedListBox() const;
  104.  
  105.   /**
  106.     This enum indentifies the moving buttons
  107.   */
  108.   enum MoveButton {
  109.     ButtonAdd,
  110.     ButtonRemove,
  111.     ButtonUp,
  112.     ButtonDown
  113.   };
  114.  
  115.   /**
  116.     This enum identifies the icon sizes, used for the move buttons.
  117.     The values correspond to the following pixel sizes:
  118.     @li SmallIcon - the return value of IconSize( KIcon::Small ), the user defined size
  119.                 of a small icon in KDE. This is the default setting.
  120.     @li Small - 16px
  121.     @li Medium - 22px
  122.     @li Large - 32px
  123.     @li XLarge - 48px
  124.   */
  125.   enum ButtonIconSize {
  126.     SmallIcon,
  127.     Small,
  128.     Medium,
  129.     Large,
  130.     XLarge
  131.   };
  132.  
  133.   /**
  134.     This enum defines policies for where to insert moved items in a listbox.
  135.     The following policies are currently defined:
  136.     @li BelowCurrent - The item is inserted below the listbox'
  137.         currentItem() or at the end if there is no curent item.
  138.     @li Sorted - The listbox is sort()ed after one or more items are inserted.
  139.     @li AtTop - The item is inserted at index 0 in the listbox.
  140.     @li AtBottom - The item is inserted at the end of the listbox.
  141.  
  142.     @sa availableInsertionPolicy(), setAvailableInsertionPolicy(),
  143.     selectedInsertionPolicy(), setSelectedInsertionPolicy().
  144.   */
  145.   enum InsertionPolicy {
  146.     BelowCurrent,
  147.     Sorted,
  148.     AtTop,
  149.     AtBottom
  150.   };
  151.  
  152.   /**
  153.     @return Wheather moveOnDoubleClcik is enabled.
  154.  
  155.     If enabled, an item in any listbox will be moved to the other one whenever
  156.     doubleclicked.
  157.     @sa setMoveOnDoubleClick()
  158.   */
  159.   bool moveOnDoubleClick() const;
  160.  
  161.   /**
  162.     Sets moveOnDoubleClick to @p enable
  163.     @sa moveOnDoubleClick()
  164.   */
  165.   void setMoveOnDoubleClick( bool enable );
  166.  
  167.   /**
  168.     @return Weather keyboard control is enabled.
  169.  
  170.     When Keyboard control is enabled, the widget will react to
  171.     the following keyboard actions:
  172.     @li CTRL + Right - simulate clicking the add button
  173.     @li CTRL + Left - simulate clicking the remove button
  174.     @li CTRL + Up - simulate clicking the up button
  175.     @li CTRL + Down - simulate clicking the down button
  176.  
  177.     Additionally, pressing RETURN or ENTER on one of the list boxes
  178.     will cause the current item of that listbox to be moved to the other
  179.     listbox.
  180.  
  181.     The keyboard actions are enabled by default.
  182.  
  183.     @sa setKeyboardEnabled()
  184.   */
  185.   bool keyboardEnabled() const;
  186.  
  187.   /**
  188.     Sets the keyboard enabled depending on @p enable.
  189.     @sa keyboardEnabled()
  190.   */
  191.   void setKeyboardEnabled( bool enable );
  192.  
  193.   /**
  194.     @return The text of the label for the available items listbox.
  195.   */
  196.   QString availableLabel() const;
  197.  
  198.   /**
  199.     Sets the label for the available items listbox to @p text.
  200.     Note that this label has the listbox as its @e buddy, so that
  201.     if you have a single ampersand in the text, the following character
  202.     will become the accellerator to focus te listbox.
  203.   */
  204.   void setAvailableLabel( const QString & text );
  205.  
  206.   /**
  207.     @return the label of the selected items listbox.
  208.   */
  209.   QString selectedLabel() const;
  210.  
  211.   /**
  212.     Sets the label for the selected items listbox to @p text.
  213.     Note that this label has the listbox as its @e buddy, so that
  214.     if you have a single ampersand in the text, the following character
  215.     will become the accellerator to focus te listbox.
  216.   */
  217.   void setSelectedLabel( const QString & text );
  218.  
  219.   /**
  220.     @return the current ButtonIconSize.
  221.   */
  222.   ButtonIconSize buttonIconSize() const;
  223.  
  224.   /**
  225.     Sets the button icon size.
  226.     See ButtonIconSize for the possible values and their pixel meaning.
  227.   */
  228.   void setButtonIconSize( ButtonIconSize size );
  229.  
  230.   /**
  231.     @return The current insertion policy for the available listbox.
  232.     The default policy for the available listbox is Sorted.
  233.     See also InsertionPolicy, setAvailableInsertionPolicy().
  234.   */
  235.   InsertionPolicy availableInsertionPolicy() const;
  236.  
  237.   /**
  238.     Sets the insertion policy for the available listbox.
  239.     See also InsertionPolicy, availableInsertionPolicy().
  240.   */
  241.   void setAvailableInsertionPolicy( InsertionPolicy policy );
  242.  
  243.   /**
  244.     @return The current insertion policy for the selected listbox.
  245.     The default policy for the selected listbox is BelowCurrent.
  246.     See also InsertionPolicy, setSelectedInsertionPolicy().
  247.   */
  248.   InsertionPolicy selectedInsertionPolicy() const;
  249.  
  250.   /**
  251.     Sets the insertion policy for the selected listbox.
  252.     See also InsertionPolicy, selectedInsertionPolicy().
  253.   */
  254.   void setSelectedInsertionPolicy( InsertionPolicy policy );
  255.  
  256.   /**
  257.     @return wheather the Up and Down buttons should be displayed.
  258.   */
  259.   bool showUpDownButtons() const;
  260.  
  261.   /**
  262.     Sets wheather the Up and Down buttons should be displayed
  263.     according to @p show
  264.   */
  265.   void setShowUpDownButtons( bool show );
  266.  
  267.   /**
  268.     Sets the pixmap of the button @p button to @p icon.
  269.     It calls SmallIconSet(pm) to generate the icon set.
  270.   */
  271.   void setButtonIcon( const QString &icon, MoveButton button );
  272.  
  273.   /**
  274.     Sets the iconset for button @p button to @p iconset.
  275.     You can use this method to et a costum icon set. Either
  276.     created by QIconSet, or use the application instance of
  277.     KIconLoader (recommended).
  278.   */
  279.   void setButtonIconSet( const QIconSet &iconset, MoveButton button );
  280.  
  281.   /**
  282.     Sets the tooltip for the button @p button to @p tip.
  283.   */
  284.   void setButtonTooltip( const QString &tip, MoveButton button );
  285.  
  286.   /**
  287.     Sets the whatsthis help for button @p button to @p text.
  288.   */
  289.   void setButtonWhatsThis( const QString &text, MoveButton button );
  290.  
  291.   /**
  292.      Sets the enabled state of all moving buttons to reflect the current
  293.      options.
  294.  
  295.      Be sure to call this if you add or removes items to either listbox after the
  296.      widget is show()n
  297.   */
  298.   void setButtonsEnabled();
  299.  
  300. signals:
  301.   /**
  302.     Emitted when an item is moved to the "selected" listbox.
  303.   */
  304.   void added( QListBoxItem *item );
  305.  
  306.   /**
  307.     Emitted when an item is moved out of the "selected" listbox.
  308.   */
  309.   void removed( QListBoxItem *item );
  310.  
  311.   /**
  312.     Emitted when an item is moved upwards in the "selected" listbox.
  313.   */
  314.   void movedUp( QListBoxItem *item );
  315.  
  316.   /**
  317.     Emitted when an item is moved downwards in the "selected" listbox.
  318.   */
  319.   void movedDown( QListBoxItem *item );
  320.  
  321.   /**
  322.     Emitted when an item is moved to the "selected" listbox.
  323.   */
  324. //  void addedToSelection( QListBoxItem *item );
  325.  
  326. public slots:
  327.   /**
  328.     Reimplemented for internal reasons.
  329.     (calls setButtonsEnabled())
  330.   */
  331.   void polish();
  332.  
  333. protected:
  334.   /**
  335.     Reimplamented for internal reasons.
  336.   */
  337.   void keyPressEvent( QKeyEvent * );
  338.  
  339.   /**
  340.     Reimplemented for internal reasons.
  341.   */
  342.   bool eventFilter( QObject *, QEvent * );
  343.  
  344. private slots:
  345.   /**
  346.     Move selected item from available box to the selected box
  347.   */
  348.   void buttonAddClicked();
  349.  
  350.   /**
  351.     Move selected item from selected box to available box
  352.   */
  353.   void buttonRemoveClicked();
  354.  
  355.   /**
  356.     Move selected item in selected box upwards
  357.   */
  358.   void buttonUpClicked();
  359.  
  360.   /**
  361.     Move seleted item in selected box downwards
  362.   */
  363.   void buttonDownClicked();
  364.  
  365.   /**
  366.     Moves the item @p item to the other listbox if moveOnDoubleClick is enabled.
  367.   */
  368.   void  itemDoubleClicked( QListBoxItem *item );
  369.  
  370.   /**
  371.     connected to both list boxes to set the buttons enabled
  372.   */
  373.   void slotCurrentChanged( QListBoxItem * ) { setButtonsEnabled(); }
  374.  
  375. private:
  376.  
  377.   /**
  378.     Move item @p item to the other listbox
  379.   */
  380.   void moveItem( QListBoxItem *item );
  381.  
  382.   /**
  383.     loads the icons for the move buttons.
  384.   */
  385.   void loadIcons();
  386.  
  387.   /**
  388.     @return the index to insert an item into listbox @p lb,
  389.     given InsertionPolicy @p policy.
  390.  
  391.     Note that if policy is Sorted, this will return -1.
  392.     Sort the listbox after inserting the item in that case.
  393.   */
  394.   int insertionIndex( QListBox *lb, InsertionPolicy policy );
  395.  
  396.   /** @private
  397.     Private data storage
  398.   */
  399.   KActionSelectorPrivate *d;
  400. };
  401.  
  402. #endif // _KACTION_SELECTOR_H_
  403.